<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>What is pywinauto &mdash; pywinauto 0.5.4 documentation</title>
    
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '0.5.4',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="pywinauto 0.5.4 documentation" href="contents.html" />
    <link rel="next" title="Automating an application" href="getting_started.html" />
    <link rel="prev" title="Contents" href="contents.html" /> 
  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="getting_started.html" title="Automating an application"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="contents.html" title="Contents"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="contents.html">pywinauto 0.5.4 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="what-is-pywinauto">
<h1>What is pywinauto<a class="headerlink" href="#what-is-pywinauto" title="Permalink to this headline">¶</a></h1>
<p>0.6+ development is on the roadmap of the Open Source community (<a class="reference external" href="https://github.com/pywinauto">https://github.com/pywinauto</a>)</p>
<p>Current 0.5.x maintainance is lead by © Intel Corporation, 2015</p>
<p>© Mark Mc Mahon, 2006-2014</p>
<p>Released under the LGPL v2.1 or later</p>
<p><a class="reference internal" href="contents.html#contents-root"><span>Full table of contents.</span></a></p>
<div class="section" id="what-is-it">
<h2>What is it?<a class="headerlink" href="#what-is-it" title="Permalink to this headline">¶</a></h2>
<p>pywinauto is a set of python modules to automate the Microsoft Windows GUI.
At it&#8217;s simplest it allows you to send mouse and keyboard actions to windows
dialogs and controls.</p>
</div>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>Install the following Python packages<ul>
<li><em>Required</em> pyWin32                    <a class="reference external" href="http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/">http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/</a></li>
<li><em>Optional</em> Pillow (fork of PIL)          <a class="reference external" href="https://pypi.python.org/pypi/Pillow/2.7.0">https://pypi.python.org/pypi/Pillow/2.7.0</a></li>
</ul>
</li>
<li>Download latest pywinauto from <a class="reference external" href="https://github.com/pywinauto/pywinauto/releases">https://github.com/pywinauto/pywinauto/releases</a></li>
<li>Unzip the pywinauto zip file to a folder</li>
<li>Run <code class="docutils literal"><span class="pre">python.exe</span> <span class="pre">setup.py</span> <span class="pre">install</span></code></li>
</ul>
</div>
<div class="section" id="installation-in-silent-mode">
<h2>Installation in silent mode<a class="headerlink" href="#installation-in-silent-mode" title="Permalink to this headline">¶</a></h2>
<p>(Python 2.7, 3.1, 3.2, 3.3, 3.4, 3.5)</p>
<ul class="simple">
<li>Just run <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pywinauto</span></code></li>
</ul>
<p>To check you have it installed correctly
Run Python</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">pywinauto.application</span> <span class="kn">import</span> <span class="n">Application</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">app</span> <span class="o">=</span> <span class="n">Application</span><span class="o">.</span><span class="n">start</span><span class="p">(</span><span class="s">&quot;notepad.exe&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">app</span><span class="o">.</span><span class="n">UntitledNotepad</span><span class="o">.</span><span class="n">TypeKeys</span><span class="p">(</span><span class="s">&quot;</span><span class="si">%F</span><span class="s">X&quot;</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="how-does-it-work">
<h2>How does it work<a class="headerlink" href="#how-does-it-work" title="Permalink to this headline">¶</a></h2>
<p>A lot is done through attribute access (<code class="docutils literal"><span class="pre">__getattr__</span></code>) for each class. For example
when you get the attribute of an Application or Dialog object it looks for a
dialog or control (respectively).</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">myapp</span><span class="o">.</span><span class="n">Notepad</span> <span class="c"># looks for a Window/Dialog of your app that has a title &#39;similar&#39;</span>
              <span class="c"># to &quot;Notepad&quot;</span>

<span class="n">myapp</span><span class="o">.</span><span class="n">PageSetup</span><span class="o">.</span><span class="n">OK</span> <span class="c"># looks first for a dialog with a title like &quot;PageSetup&quot;</span>
                   <span class="c"># then it looks for a control on that dialog with a title</span>
                   <span class="c"># like &quot;OK&quot;</span>
</pre></div>
</div>
<p>This attribute resolution is delayed (currently a hard coded amount of time) until
it succeeds. So for example if you Select a menu option and then look for the
resulting dialog e.g.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">UntitledNotepad</span><span class="o">.</span><span class="n">MenuSelect</span><span class="p">(</span><span class="s">&quot;File-&gt;SaveAs&quot;</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">SaveAs</span><span class="o">.</span><span class="n">ComboBox5</span><span class="o">.</span><span class="n">Select</span><span class="p">(</span><span class="s">&quot;UTF-8&quot;</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">SaveAs</span><span class="o">.</span><span class="n">edit1</span><span class="o">.</span><span class="n">SetText</span><span class="p">(</span><span class="s">&quot;Example-utf8.txt&quot;</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">SaveAs</span><span class="o">.</span><span class="n">Save</span><span class="o">.</span><span class="n">Click</span><span class="p">()</span>
</pre></div>
</div>
<p>At the 2nd line the SaveAs dialog might not be open by the time this line is
executed. So what happens is that we wait until we have a control to resolve
before resolving the dialog. At that point if we can&#8217;t find a SaveAs dialog with
a ComboBox5 control then we wait a very short period of time and try again,
this is repeated up to a maximum time (currently 5 seconds!)</p>
<p>This avoid the user having to use time.sleep or a &#8220;Wait&#8221; function.</p>
<p>If your application performs long time operation, new dialog can appear or
disappear later. You can wait for its new state like so</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">app</span><span class="o">.</span><span class="n">Open</span><span class="o">.</span><span class="n">Open</span><span class="o">.</span><span class="n">Click</span><span class="p">()</span> <span class="c"># opening large file</span>
<span class="n">app</span><span class="o">.</span><span class="n">Open</span><span class="o">.</span><span class="n">WaitNot</span><span class="p">(</span><span class="s">&#39;visible&#39;</span><span class="p">)</span> <span class="c"># make sure &quot;Open&quot; dialog became invisible</span>
<span class="c"># wait for up to 30 seconds until data.txt is loaded</span>
<span class="n">app</span><span class="o">.</span><span class="n">Window</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s">&#39;data.txt - Notepad&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">Wait</span><span class="p">(</span><span class="s">&#39;ready&#39;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="mi">30</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="some-similar-tools-for-comparison">
<h2>Some similar tools for comparison<a class="headerlink" href="#some-similar-tools-for-comparison" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>Python tools<ul>
<li>PyAutoGui (<a class="reference external" href="https://github.com/asweigart/pyautogui">https://github.com/asweigart/pyautogui</a>) - it&#8217;s a cross-platform but there is no windows/controls manipulation at all.</li>
<li>AXUI (<a class="reference external" href="https://github.com/xcgspring/AXUI">https://github.com/xcgspring/AXUI</a>) - this is one of the wrappers around UI Automation API.</li>
<li>winGuiAuto (<a class="reference external" href="http://www.brunningonline.net/simon/blog/archives/winGuiAuto.py.html">http://www.brunningonline.net/simon/blog/archives/winGuiAuto.py.html</a>) - another module using Win32 API.</li>
</ul>
</li>
<li>Other scripting language tools<ul>
<li>Perl Win32::GuiTest  (http://winguitest.sourceforge.net/)</li>
<li>Ruby Win32-Autogui (<a class="reference external" href="https://github.com/robertwahler/win32-autogui">https://github.com/robertwahler/win32-autogui</a>)</li>
<li>Ruby RAutomation (<a class="reference external" href="https://github.com/jarmo/RAutomation">https://github.com/jarmo/RAutomation</a>) - there are 3 adapters: Win32 API, UIA, AutoIt.</li>
<li>C# Winium.Desktop (<a class="reference external" href="https://github.com/2gis/Winium.Desktop">https://github.com/2gis/Winium.Desktop</a>)</li>
<li>others (<a class="reference external" href="http://www.opensourcetesting.org/functional.php">http://www.opensourcetesting.org/functional.php</a>)</li>
</ul>
</li>
<li>Other free tools<ul>
<li>AutoIt (<a class="reference external" href="http://www.autoitscript.com/">http://www.autoitscript.com/</a>)</li>
<li>See collection at: <a class="reference external" href="https://github.com/atinfo/awesome-test-automation">https://github.com/atinfo/awesome-test-automation</a></li>
</ul>
</li>
<li>Commercial tools<ul>
<li>WinRunner (<a class="reference external" href="http://www.mercury.com/us/products/quality-center/functional-testing/winrunner/">http://www.mercury.com/us/products/quality-center/functional-testing/winrunner/</a>)</li>
<li>SilkTest (<a class="reference external" href="http://www.segue.com/products/functional-regressional-testing/silktest.asp">http://www.segue.com/products/functional-regressional-testing/silktest.asp</a>)</li>
<li>Many Others (<a class="reference external" href="http://www.testingfaqs.org/t-gui.html">http://www.testingfaqs.org/t-gui.html</a>)</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="why-write-yet-another-automation-tool-if-there-are-so-many-out-there">
<h2>Why write yet another automation tool if there are so many out there?<a class="headerlink" href="#why-write-yet-another-automation-tool-if-there-are-so-many-out-there" title="Permalink to this headline">¶</a></h2>
<p>There are loads of reasons :-)</p>
<dl class="docutils">
<dt><strong>Takes a different approach:</strong></dt>
<dd><p class="first">Most other tools are not object oriented you end  up writing stuff like:</p>
<div class="highlight-python"><div class="highlight"><pre>window = findwindow(title = &quot;Untitled - Notepad&quot;, class = &quot;Notepad&quot;)
SendKeys(window, &quot;%OF&quot;)  # Format -&gt; Font
fontdialog  = findwindow(&quot;title = &quot;Font&quot;)
buttonClick(fontdialog, &quot;OK&quot;)
</pre></div>
</div>
<p>I was hoping to create something more userfriendly (and pythonic). For example
the translation of above would be:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="n">win</span> <span class="o">=</span> <span class="n">app</span><span class="o">.</span><span class="n">UntitledNotepad</span>
<span class="n">win</span><span class="o">.</span><span class="n">MenuSelect</span><span class="p">(</span><span class="s">&quot;Format-&gt;Font&quot;</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">Font</span><span class="o">.</span><span class="n">OK</span><span class="o">.</span><span class="n">Click</span><span class="p">()</span>
</pre></div>
</div>
</dd>
<dt><strong>Python makes it easy:</strong></dt>
<dd>Python is a great programming language, but I didn&#8217;t find
any automation tools that were Pythonic (I only found one
that was implemented in python) and I didn&#8217;t care for it
too much.</dd>
<dt><strong>Localization as a main requirement:</strong></dt>
<dd><p class="first">I work in the localization industry and GUI
automation is used extensively as often all
you need to do is ensure that your UI behaves
and is correct with respect to the Source
UI. This is actually an easier job then for
testing the original source UI.</p>
<p class="last">But most automation tools are based off of coordinates or text of the
controls and these can change in the localized software. So my goal (
though not yet implemented) is to allow scripts to run unchanged
between original source language (often English) and the translated
software (Japanese, German, etc).</p>
</dd>
</dl>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">What is pywinauto</a><ul>
<li><a class="reference internal" href="#what-is-it">What is it?</a></li>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#installation-in-silent-mode">Installation in silent mode</a></li>
<li><a class="reference internal" href="#how-does-it-work">How does it work</a></li>
<li><a class="reference internal" href="#some-similar-tools-for-comparison">Some similar tools for comparison</a></li>
<li><a class="reference internal" href="#why-write-yet-another-automation-tool-if-there-are-so-many-out-there">Why write yet another automation tool if there are so many out there?</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="contents.html"
                        title="previous chapter">Contents</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="getting_started.html"
                        title="next chapter">Automating an application</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/index.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="getting_started.html" title="Automating an application"
             >next</a> |</li>
        <li class="right" >
          <a href="contents.html" title="Contents"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="contents.html">pywinauto 0.5.4 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &copy; Copyright 2015, Mark Mc Mahon.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.1.
    </div>
  </body>
</html>